home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 3 / Gold Medal Software - Volume 3 (Gold Medal) (1994).iso / utils2 / t2b120a.arj / TXT2BIN.DOC < prev    next >
Text File  |  1994-01-27  |  16KB  |  532 lines
  1.            TXT2BIN - Text-To-Binary Conversion Program
  2.                   Version 1.20 (January 3, 1994)
  3.                 Copyright 1992,1993,1994 Bruce Lum
  4.  
  5.  
  6.  
  7. DISCLAIMER
  8. ----------
  9.  
  10. The TXT2BIN program is provided "AS-IS".  You use this program
  11. strictly at your own risk.  No warranty of any kind exists.  The
  12. author is not responsible for any incidental or consequential
  13. damages to your computer or the data stored on it as a result of
  14. misuse or the inability to run the program.  By running TXT2BIN,
  15. you agree to this.
  16.  
  17.  
  18.  
  19. TRADEMARKS
  20. ----------
  21.  
  22. HP, LaserJet, DeskJet and PCL are U.S. registered trademarks of
  23. Hewlett-Packard Company.
  24.  
  25. IBM and Proprinter are registered trademarks of International
  26. Business Machines Corporation.
  27.  
  28. Epson is a registered trademark of Seiko Epson Corporation.
  29.  
  30.  
  31.  
  32. INTRODUCTION
  33. ------------
  34.  
  35. TXT2BIN is a utility program for the IBM PC (or compatible) that
  36. helps you to create and maintain a binary file by describing the
  37. contents in the form of a text file.
  38.  
  39. In contrast, you could create or modify a binary file with a hex
  40. editor or a debugger.  However, you may be restricted to the use
  41. of hexadecimal numbers, in addition to ASCII text.  Also, a
  42. binary file may be all that you are left with.  Documented
  43. changes to the file may have to exist elsewhere.
  44.  
  45.  
  46. What can you do with TXT2BIN?  Here is an application:
  47.  
  48.     A text file describes the initial settings of a dot-matrix or
  49.     laser printer, with documentation in the file.  TXT2BIN
  50.     translates this text file into the equivalent binary
  51.     information and sends it to the printer.
  52.  
  53.  
  54. With TXT2BIN, you can work with any base (e.g. decimal,
  55. hexadecimal, etc.) that you feel comfortable with.  Any changes
  56. can be accompanied by comments in the text file.  Symbols can
  57. also be used to represent bytes in a more legible way.
  58.  
  59. To use TXT2BIN, all you need is a text editor to describe the
  60. contents of the binary file.  From the text file, TXT2BIN creates
  61. the binary file for you.  If the binary file ever needs any
  62. changes, you can make them in the text file and run TXT2BIN
  63. again.
  64.  
  65.  
  66.  
  67. COMMAND SYNTAX
  68. --------------
  69.  
  70. To run TXT2BIN from the DOS prompt, use the following syntax:
  71.  
  72.     TXT2BIN  [option...]  <textfile>  <target>
  73.  
  74. where:
  75.  
  76.     [option] is one or more special instructions to be used
  77.     during the conversion process;
  78.  
  79.     <textfile> is the name of the file that contains the textual
  80.     representation of the individual bytes in the binary file;
  81.  
  82.     <target> is the name of the file or device that will receive
  83.     the bytes resulting from the conversion process.
  84.  
  85.  
  86.  
  87. THE TEXT FILE
  88. -------------
  89.  
  90. The text file consists of one or more lines (or records) that
  91. describe the contents of the binary file.
  92.  
  93. To create the text file, use a text editor or word processor that
  94. can save files in the ASCII text format.  Non-ASCII files may
  95. produce error messages during the conversion process.
  96.  
  97. You can use any ASCII character whose value falls within the
  98. following ranges (inclusive):
  99.  
  100.     (a) 21 - FF (hexadecimal), or 33 - 255 (decimal);
  101.  
  102.     (b) SPACE:      20 (hex) or 32 (dec);
  103.  
  104.     (c) TAB:        9 (hex/dec);
  105.  
  106.     (d) FORM-FEED:  0C (hex) or 12 (dec)
  107.  
  108.  
  109. Each line in the text file can contain any of the following:
  110.  
  111.     (a) a list of bytes
  112.     (b) a text string
  113.     (c) a comment
  114.     (d) a directive
  115.     (e) a combination of the above
  116.     (f) a blank line
  117.  
  118.  
  119. The first four (4) types are discussed in detail below.
  120.  
  121.  
  122.  
  123. Representation of Individual Bytes
  124. ----------------------------------
  125.  
  126. Each byte must be composed of alphabetic and/or numeric
  127. characters conforming to the radix (base) that is currently in
  128. effect.
  129.  
  130.     Examples:
  131.  
  132.         If the radix is 2, then the characters that
  133.         make up the byte can only be 0 and 1.
  134.  
  135.         If the radix is 8, then the characters that
  136.         make up the byte can only be from 0 to 7 (inclusive).
  137.  
  138.  
  139. With a radix greater than 10, use the alphabetic characters
  140. (starting from the letter A) to represent the digits higher than
  141. 9.
  142.  
  143.     Examples:
  144.  
  145.         If the radix is 12, then the characters that make up
  146.         the byte can only be from 0 to 9 (inclusive), and the
  147.         letters A and B (to represent 10 and 11, respectively).
  148.  
  149.         If the radix is 16, then the characters that make up
  150.         the byte can only be from 0 to 9 (inclusive) and from A
  151.         to F (inclusive).  The letters from A to F will represent
  152.         the digits from 10 to 15, respectively.
  153.  
  154.  
  155. Regardless of the radix, the total value of each byte must be
  156. between 0 to 255 (inclusive).
  157.  
  158. Leading zeroes are not required, and you must have spaces between
  159. the bytes.
  160.  
  161.  
  162.     Examples (all representing a set of identical bytes):
  163.  
  164.         1B 26 6C 31 4F          (radix=16: HEXADECIMAL)
  165.  
  166.         27 38 108 49 79         (radix=10: DECIMAL)
  167.  
  168.         33 46 154 61 117        (radix=8: OCTAL)
  169.  
  170.         00011011 00100110 01101100 00110001 01001111
  171.                                 (radix=2: BINARY !!)
  172.  
  173.  
  174.  
  175. Text Strings
  176. ------------
  177.  
  178. The text string enclosed by a pair of double quote characters.
  179.  
  180.     Examples:
  181.  
  182.         "%-12345X"
  183.  
  184.         "A text string"
  185.  
  186.  
  187. Escape sequences may also be part of a text string.
  188.  
  189.     Example:
  190.  
  191.         "\fA text string\n"
  192.  
  193.  
  194. (For more details, see the following section called "Escape
  195. Sequences in Text Strings".)
  196.  
  197.  
  198. For double quotes, precede them with a backslash character (\).
  199. For example, if the text string is
  200.  
  201.         PARM="CD-ROM AVAILABLE";
  202.  
  203. then you must set it up as follows:
  204.  
  205.         "PARM=\"CD-ROM AVAILABLE\";"
  206.  
  207.  
  208.  
  209. Escape Sequences in Text Strings
  210. --------------------------------
  211.  
  212. The escape sequence allows certain hard-to-get characters (such
  213. as control codes) to be represented.  These characters usually
  214. cannot be entered from within the text editor or word processor.
  215.  
  216. An escape sequence starts with the backslash character (\) and is
  217. followed by one or more octal, hexadecimal or ASCII characters.
  218.  
  219. Here is the list of escape sequences that TXT2BIN currently
  220. supports:
  221.  
  222.  
  223.     Sequence    Value   Char    Description
  224.  
  225.     \a          0x07    BEL     Bell (Alert)
  226.     \b          0x08    BS      Backspace
  227.     \f          0x0C    FF      Formfeed
  228.     \n          0x0A    LF      Newline
  229.     \r          0x0D    CR      Carriage return
  230.     \t          0x09    HT      Horizontal tab
  231.     \v          0x0B    VT      Vertical tab
  232.     \'          0x27    '       Single quote (apostrophe)
  233.     \?          0x3F    ?       Question mark
  234.     \"          0x22    "       Double quote
  235.     \\          0x5C    \       Backslash
  236.  
  237.     \Onnn               (any)   'nnn' is a string of up to 3
  238.                                 octal digits
  239.  
  240.     \Xhh                (any)   'hh' is a string of hex digits
  241.     \xhh                (any)   'hh' is a string of hex digits
  242.  
  243.     \nnn                (any)   'nnn' is a string of up to 3
  244.                                 octal digits
  245.  
  246.  
  247. Examples:
  248.  
  249.     "\aFatal error!\r\n"
  250.  
  251.     "The \"right\" way of using double-quotes"
  252.  
  253.     "The ESC code is represented by \033"
  254.     "The ESC code is represented by \x1B"
  255.     "The ESC code is represented by \X1B"
  256.     "The ESC code is represented by \O033"
  257.  
  258.  
  259.  
  260. Comments
  261. --------
  262.  
  263. A comment starts with a semi-colon.  Anything to the right of the
  264. semi-colon is completely ignored by TXT2BIN.  The comment can
  265. start anywhere on the line.
  266.  
  267.     Example:
  268.  
  269.         ;-------------------------------------------------
  270.         ; These three entire lines are ignored by TXT2BIN
  271.         ;-------------------------------------------------
  272.  
  273.         27 "1@"     ; This part of the line will be ignored
  274.  
  275.  
  276.  
  277. Directives
  278. ----------
  279.  
  280. These are instructions asking TXT2BIN to take some form of
  281. action.  Although directives can appear anywhere in the text
  282. file, and as often as required, only one directive is allowed on
  283. a line.
  284.  
  285. A directive starts with a period (.) and is followed by a special
  286. keyword.  Other parameters may follow the keyword.
  287.  
  288.  
  289. This version of TXT2BIN supports the following directives:
  290.  
  291.     (a) DEFINE
  292.     (b) INCLUDE
  293.     (c) RADIX
  294.  
  295. These directives are described below.
  296.  
  297.  
  298.  
  299. .DEFINE  Symbol  Replacement
  300.  
  301.     What this means to TXT2BIN is "After this line, if you ever
  302.     encounter <Symbol> later in the text file (except within a
  303.     comment), replace it with the contents of Replacement".  This
  304.     is useful if one or more bytes can be commonly identified by
  305.     a symbolic name.
  306.  
  307.     The name of the symbol, "Symbol", must start with an
  308.     alphabetic character (A-Z, a-z), followed by a mixture of
  309.     alphabetic, numeric (0-9), and underscore (_) characters.
  310.     The maximum length of a symbol is 32 characters.
  311.  
  312.     Within the name of a symbol, an alphabetic letter can either
  313.     be lowercase or uppercase; there is no distinction.  Thus,
  314.     the symbols "Esc" and "ESC" are considered as identical.
  315.  
  316.     "Replacement" is a sequence of bytes, strings, and symbols
  317.     that you intend to replace <Symbol> with during the
  318.     conversion process.  You may also include comments.  The
  319.     maximum length of "Replacement" is 255 characters (including
  320.     comments).
  321.  
  322.     Example:
  323.  
  324.         .DEFINE Esc   27        ; Replace <Esc> with 27
  325.         .DEFINE CR_LF 13 10     ; Replace <CR_LF> with 13 10
  326.  
  327.             <Esc> "&l1T" <CR_LF>
  328.  
  329.         ; TXT2BIN replaces <Esc> and <CR_LF>, so that the
  330.         ; line will be processed as:
  331.         ;
  332.         ;     27 "&l1T" 13 10
  333.  
  334.  
  335. .INCLUDE  FileName
  336.  
  337.     This directive allows you to insert lines from a specified
  338.     file into your text file.
  339.  
  340.     When this directive is encountered, TXT2BIN reads and
  341.     processes the lines in the file called "FileName".  After all
  342.     the lines are processed, TXT2BIN continues with the line
  343.     following the INCLUDE directive.
  344.  
  345.     The two files DEFINES.10 and DEFINES.16 (contained in your
  346.     TXT2BIN package) defines the list of ASCII control characters
  347.     (in decimal and the other in hexadecimal, respectively).
  348.     Instead of having to type the definitions repeatingly for all
  349.     your text files, you can use the INCLUDE directive to refer
  350.     to one of the two files.
  351.  
  352.     Examples:
  353.  
  354.         .INCLUDE  defines.10
  355.  
  356.         .INCLUDE  Z:\PUBLIC\TXT2BIN\INCLUDE\defines.16
  357.  
  358.  
  359. .RADIX nn
  360.  
  361.     This changes the radix (number base) to any value between 2
  362.     to 36, inclusive.  'nn' is the value of the desired radix, in
  363.     decimal.  The default radix value is 10 (that is, the decimal
  364.     numbering system).
  365.  
  366.     Examples:
  367.  
  368.         .RADIX 10   ; Change base to 10 (DECIMAL)
  369.  
  370.         .RADIX 16   ; Change base to 16 (HEXADECIMAL)
  371.  
  372.         .RADIX 8    ; Change base to 8  (OCTAL)
  373.  
  374.         .RADIX 2    ; Change base to 2  (BINARY)
  375.  
  376.  
  377.  
  378. ERROR MESSAGES
  379. --------------
  380.  
  381. During TXT2BIN's processing of the contents of the text file,
  382. messages may appear as a result of one or more encountered
  383. errors.  Each message will also identify the exact location of
  384. the error by telling you the line and column number.
  385.  
  386.  
  387. Error messages can also be redirected to a file or device.  Here
  388. are some examples:
  389.  
  390.     TXT2BIN filename.txt filename.bin >error.msg
  391.  
  392.     TXT2BIN filename.txt filename.bin >NUL
  393.  
  394.     TXT2BIN filename.txt filename.bin >LPT1
  395.  
  396.  
  397. The complete list of error messages can be found in the file
  398. called TXT2BIN.MSG that comes with the TXT2BIN program.
  399.  
  400.  
  401.  
  402. COMMAND-LINE OPTIONS
  403. --------------------
  404.  
  405. Only one option is currently available in TXT2BIN that you can
  406. use during the conversion process.
  407.  
  408.     -q      QUIET switch.  This option eliminates all status and
  409.             error messages that are normally displayed on the
  410.             screen.
  411.  
  412.                 Example:
  413.  
  414.                     TXT2BIN -q INFILE.TXT OUTFILE.BIN
  415.  
  416.  
  417.  
  418. EXAMPLE
  419. -------
  420.  
  421. The following text file contains a set of commands that
  422. initializes a HP LaserJet IIISi printer.
  423.  
  424. (This can be found in the file called EXAMPLE.HPL that comes with
  425. the TXT2BIN program.)
  426.  
  427.  
  428.     ;-----------------------------------------------------------
  429.     ; EXAMPLE.HPL
  430.     ;
  431.     ; This text file contains the instructions to initialize a
  432.     ; HP LaserJet IIISi (or 4) printer
  433.     ;
  434.     ; (Use the TXT2BIN program to create the binary image file)
  435.     ;
  436.     ; HP, PCL and LaserJet are U.S. registered trademarks of
  437.     ; Hewlett-Packard Company.
  438.     ;-----------------------------------------------------------
  439.  
  440.         .RADIX 16                   ; Set base to hexadecimal
  441.  
  442.         .INCLUDE defines.16         ; Include list of control
  443.                                     ; codes (in hexadecimal)
  444.  
  445.     ;--------------------------------------
  446.     ; Job Control
  447.     ;--------------------------------------
  448.     <Esc> "%-12345X"                ; Universal Exit Language /
  449.                                     ;   Start of PJL
  450.  
  451.     "@PJL ENTER LANGUAGE=PCL" <LF>  ; Enter PCL mode
  452.  
  453.     <Esc> "E"                       ; Reset the printer
  454.     <Esc> "&l1X"                    ; Number of copies = 1
  455.     <Esc> "&l1S"                    ; Duplex, long-edge binding
  456.  
  457.     ;--------------------------------------
  458.     ; Page Control
  459.     ;--------------------------------------
  460.     <Esc> "&l0O"                    ; Page orientation: Portrait
  461.     <Esc> "&l2A"                    ; Page size: Letter
  462.     <Esc> "&l6D"                    ; Line spacing: 6 lines/inch
  463.     <Esc> "&l1E"                    ; Select upper output bin
  464.     <Esc> "&l60F"                   ; Text length: 60 lines
  465.     <Esc> "&l1H"                    ; Main paper source feed
  466.  
  467.  
  468.  
  469. DISTRIBUTION
  470. ------------
  471.  
  472. You may freely distribute the TXT2BIN package, provided that the
  473. following files are distributed together:
  474.  
  475.     TXT2BIN.EXE     The TXT2BIN program
  476.     TXT2BIN.DOC     The documentation file for TXT2BIN
  477.     TXT2BIN.MSG     List of error messages from TXT2BIN
  478.  
  479.     README.1ST      Installation procedure, list of latest
  480.                     changes, and any last-minute information
  481.                     (this file)
  482.  
  483.     DEFINES.10      List of ASCII control character definitions
  484.                     (in decimal or base 10)
  485.  
  486.     DEFINES.16      List of ASCII control character definitions
  487.                     (in hexadecimal or base 16)
  488.  
  489.     EXAMPLE.ESN     Text file to reset Epson LQ-2500 printer
  490.     EXAMPLE.HPD     Text file to reset HP DeskJet printer
  491.     EXAMPLE.HPL     Text file to reset HP LaserJet printer
  492.     EXAMPLE.IBM     Text file to reset IBM Proprinter printer
  493.  
  494.  
  495.     BIN2TXT.EXE     A supplemental program that converts a binary
  496.                     file into a textual representation
  497.  
  498.     BIN2TXT.DOC     The documentation file for BIN2TXT
  499.  
  500.  
  501.  
  502. CONTRIBUTIONS
  503. -------------
  504.  
  505. If you find TXT2BIN useful, please send $10.00 (in U.S. funds) or
  506. $12.00 (in Canadian funds) to the author at the postal address
  507. below.  If you have access to Compuserve or Internet, please
  508. include your ID/address; you will be notified of any updates or
  509. new products.
  510.  
  511. Your support is greatly appreciated.
  512.  
  513.  
  514.  
  515. CORRESPONDENCE
  516. --------------
  517.  
  518. If you have any problems, questions, or any type of feedback,
  519. electronic mail may be sent to the author (Bruce Lum) at the
  520. following addresses:
  521.  
  522.     Compuserve:     72727,3104
  523.     Internet:       72727.3104@compuserve.com
  524.  
  525.  
  526. If you are using the postal service, the address is:
  527.  
  528.     Bruce Lum
  529.     P.O. Box 5098, Station A
  530.     Toronto, Ontario
  531.     CANADA  M5W 1N4
  532.